The Threads subsystem contains classes which assist you in using threads in OpenDoc parts. This subsystem is used by ODF's Cyberdog support; for Cyberdog-related details, see the Internet Engineering Notes.
Table of Contents
---------------------------------
• FW_CThread Class
• Mutexes, Semaphores, etc
• Issues When Using Threads
FW_CThread Class
FW_CThread is a wrapper class for platform threads. It has methods for sleeping, suspending, and resuming a thread. It also catches exceptions that might accidentally be propogated to the entry point of a thread. Finally it declares a unique SOM Environment for each thread. FW_CThread is declared in FWODThrd.h in the OS layer.
For your convenience, the constructor takes an optional void* parameter; this will be stored in the fParameters instance variable. The procedure parameter allows you to pass a pointer to a global function into FW_CThread; this will be executed by the default implementation of Run. The combination of these two parameters allows you to run code in a thread without having to subclass FW_CThread.
FW_CThread::~FW_CThread ()
Kills the thread. You must delete every thread you create. Usually you will do this after the thread has finished running, but you may also kill a running thread (for example, if your part is deleted then you would need to terminate any threads immediately).
void FW_CThread::Sleep (long ticks)
Use this methods to put a thread to sleep. It works whether you call it from within the thread or from a different thread. A tick is 1/60th of a second. It is currently not safe to Resume or Kill a sleeping thread; you must allow it to wake up.
void FW_CThread::Suspend ()
Stops a thread from executing until Resume is called; this method can be called from within a thread or from a different one.
void FW_CThread::Resume ()
Causes a thread that has been Suspended to continue executing.
virtual void FW_CThread::Run (Environment* ev)
You may implement the code of a thread by subclassing it and overriding Run. Alternatively, if you pass a function pointer and void* parameter into the constructor, the default implementation of Run will call it (and pass the parameter).
For any thread of moderate complexity, you will want to make a subclass and implement Run, like so:
class MyCalculationThread: public FW_CThread {
public:
MyCalculationThread (MyPart* part, int parameter, const FW_CString& name);
virtual void Run (Environment* ev);
private:
MyPart* fPart;
int fLevel;
FW_CString fName;
};
MyCalculationThread::MyCalculationThread (MyPart* part, int parameter, const FW_CString& name)
: fPart (part)
fLevel (parameter),
fName (name)
{
}
void MyCalculationThread::Run (Environment* ev)
{
// do something here
int result = 1;
for (int i = 2; i <= fLevel; i++)
result *= i;
// presumably you would call the part when you are done
fPart->DidCalculation (result);
}
void MyPart::DoMenuCommand (int id)
{
if (id == cDoCalculate && !fMyThread)
fMyThread = MyCalculationThread ();
}
Mutexes, Semaphores, etc.
ODF doesn't have any public and supported classes for managing access to resources. There is a simple critical section class, FW_CThreadCriticalState, but it was only intended for internal use. Cross-platform classes will appear in ODF 3.
Issues When Using Threads
(1) Avoid creating objects on the stack.
When a thread is killed, stack-based objects are not destroyed (this is a C++ problem, not specific to OpenDoc). If you have objects which must be destroyed, declare them as members of your thread class.
Here is unsafe code:
void MyCalculationThread::Run (Environment* ev)
{
int tempValue; // Ok since it's just an int.
FW_CString tempString; // Unsafe! If this thread is killed the string will not be disposed of.
// do something with tempString
}
This is safer:
class MyCalculationThread… {
…
FW_CString fTempString;
}
void MyCalculationThread::Run (Environment* ev)
{
int tempValue; // Ok since it's just an int.
// do something with fTempString
}
In general, local stack-based objects should be declared as member variables. This is inconvenient, but C++ doesn't provide a mechanism to handle multiple stacks. We will try to provide workarounds in the future, but destruction of stack-based objects is compiler-specific and we can't be sure we'll be able to do anything about it.
(2) Make sure you delete your threads!
ODF does not keep track of threads for your; that's your responsibility. If you spawn threads you must take care to delete them; this is especially important since your part can go away before a thread is complete (for example, if it is embedded then a user can delete it).
(3) Beware of reentrancy.
Portions of OpenDoc and other parts may not react well to being called from threads (other than the main thread). For safety you should restrict threads to calling only your own code. If you do call OpenDoc, be aware that it may call back into your part (for example during frame negotiation).
ODF itself is not entirely thread-safe. For instance the graphics system won't deal well with graphic contexts existing simultaneously in multiple threads (you can do it as long as you don't Yield when a context is in scope).
(4) Threads Require Native Exceptions
ODF’s emulated exception handling is not compatible with threads. This means that you must use a compiler which supports native exceptions. CodeWarrior supports native exceptions and this is the default for ODF2, so for most people this won't be a problem.
